Skip to main content
POST
/
api
/
call
/
createBatch
# Using API Key
curl --location '{{baseUrl}}/api/call/createBatch' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "batchName": "API Campaign May 2025",
    "callingNumbers": ["64e5f12345abcdef87654321"],
    "retry": 3,
    "delay": 60,
    "timezone": "America/New_York",
    "callingHour": {"start": "09:00", "end": "17:00"},
    "allowedDays": [1,2,3,4,5]
  }'

{
  "message": "Batch created successfully",
  "status": true,
  "code": 201,
  "errorMessage": "",
  "data": "64e5f12345abcdef98765432"
}

​
Overview

Create a batch whenever you want to stage a new outbound campaign. The batch groups a friendly batchName with one or more provisioned calling numbers so you can add contacts and start dialing later. The response returns the batchId, which is required by every follow-up batch operation.

​
Prerequisites

  • API key with Calling Management scope, OR Bearer token for authenticated workspace access
  • At least one outbound phone number is active on the workspace
  • The calling numbers you pass belong to the same workspace

​
Request

​
x-api-key
string
Workspace API key. Find it under Settings → API access. Either x-api-key or Authorization header is required.
​
Authorization
string
Bearer token for authenticated workspace access. Either x-api-key or Authorization header is required.
​
batchName
string
required
Human readable campaign name shown in the Nexus dashboard.
​
callingNumbers
array[string]
required
Array of phone IDs that the dialer can rotate through while placing calls from this batch.
​
retry
number
Number of retry attempts for failed calls.
​
delay
number
Delay in seconds between retry attempts.
​
timezone
string
Timezone for the batch (e.g., “America/New_York”, “Asia/Kolkata”). Used for scheduling calls.
​
callingHour
object
Object defining calling hours. Example: {"start": "09:00", "end": "17:00"}.
​
allowedDays
array[number]
Array of allowed days for calling (0=Sunday, 1=Monday, …, 6=Saturday). Example: [1,2,3,4,5] for weekdays.
# Using API Key
curl --location '{{baseUrl}}/api/call/createBatch' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "batchName": "API Campaign May 2025",
    "callingNumbers": ["64e5f12345abcdef87654321"],
    "retry": 3,
    "delay": 60,
    "timezone": "America/New_York",
    "callingHour": {"start": "09:00", "end": "17:00"},
    "allowedDays": [1,2,3,4,5]
  }'

​
Response

{
  "message": "Batch created successfully",
  "status": true,
  "code": 201,
  "errorMessage": "",
  "data": "64e5f12345abcdef98765432"
}
​
status
boolean
required
Indicates whether the batch record was stored successfully.
​
code
integer
required
HTTP status code (201 for successful creation).
​
data
string
required
Batch ID (string) to use when adding calls, starting the dialer, or updating batch metadata.
​
message
string
required
Human readable confirmation message.

​
Error Handling

  • 400 Bad Request – Missing batchName, missing or empty callingNumbers array, or invalid input format.
  • 403 Forbidden – Invalid or missing API key, API key doesn’t match workspace, or no user found (when using Bearer token).
  • 500 Internal Server Error – Failed to create batch in database; retry or contact support with the request ID.
Authentication Options:You can authenticate using either:
  • API Key: Pass x-api-key header with your workspace API key
  • Bearer Token: Pass Authorization: Bearer <token> header
The system automatically determines the user from either authentication method. If both are provided, the API key takes precedence.
Use GET /api/call/batches/{userId} right after creation to verify that the new batch appears with the expected metadata.

Authorizations

​
Authorization
string
header
required

Bearer token authentication for workspace access

Body

application/json
​
batchName
string
required
Example:

"API Campaign May 2025"

​
callingNumbers
string[]
required
Example:
["64e5f12345abcdef87654321"]
​
retry
number
Example:

3

​
delay
number
Example:

60

​
timezone
string
Example:

"America/New_York"

​
callingHour
object
Example:
{ "start": "09:00", "end": "17:00" }
​
allowedDays
number[]
Example:
[1, 2, 3, 4, 5]

Response

Batch created successfully